Alphatype-and-Versatec TEX file format descriptions.

This file contains information about the format of files associated with
Alphatype-and-Versatec TEX.

Extension Description
.TEX = Input to TEX.
.TFI = Device-Independent Font Information File (like .TFX), used by TEX.
.DVI = Device-Independant TEX Output File, given to either preprocessor.
.ANT = Alphatype Font File, used by Alphatype preprocessor and server.
.VNT = Versatec Font File, used by Versatec preprocessor and server.
.ALF = Alphatype Preprocessor Output File, given to Alphatype server.
.VER = Versatec Preprocessor Output File, given to Versatec server.

For instance: one would run a .TEX file through TEX, which would also use the
appropriate .TFI files, and produce a .DVI file.
To get the results printed on the Versatec, one says "VSPOOL", to invoke the
Versatec preprocessor, which would use the .DVI file just produced, along
with the appropriate .TFA files, to produce a .VER file, which it then puts on
a queue for the Versatec server.  When the server gets around to it, it uses
the .VER file, along with the appropriate .VNT files, and does the actual 
output to the Versatec.

Change "Versatec" to "Alphatype", ".VNT" to ".ANT", and ".VER" to ".ALF" in the
above paragraph, and it is still correct.  Note, however, that one need not
run TEX again -- the .DVI file remains the same whether it is destined for the
Versatec or the Alphatype.

.TEX = Input to TEX.

See Stanford Artificial Intelligence Laboratory Memo AIM-317.1 or Stanford
Computer Science Department Report No. STAN-CS-78-675.1.

.TFI = Device-Independent Font Information File (like .TFX), used by TEX.

NOTE THAT THE CURRENT VERSION OF TEX DOES NOT USE THE .TFI FILE, BUT THE
OLD .TFX TYPE FILE, DOCUMENTED ON PAGE 9 OF TEXSEM (UNDER "FONT INFORMATION").


The TFI file format is exactly the same as that for a TFX file, except:

1) There are no device widths, so "nd" and the "nd" devicewidths can be
removed.  Also, the 6 bits TEX reservs for each character's device width can
be divvied up between height, width and depth, in a way yet to be determined.

2) The "tallest character in font" paramater is not needed, so the first device
dependent paramater can be set to zero.

3) [requested by ltp] The last word of the file will be some form of ID, that
must later be found to match the ID of the font file used (.VNT or .ANT).
One possibility is to use the date and time that the files were created.
This word is NOT counted in the total number of words in the file that is kept
in the first word in the file.

.DVI = Device-Independant TEX Output File, given to either preprocessor.

A .DVI file is similar to an .XGP file in function, if not appearance, but
it has the advantage that it contains enough information that it can be
easily translated to a format compatable with many different devices.  In
particular, it can be output to our Versatec or Alphatype (or both),
depending on what spooler it is passed to.  Its format follows:

The basic unit of information in a DVI file comes in an 8-bit chunk.  Here
at Stanford, they are packed four per word, in the lower-order 32 bits of each
word, and the highest order chunk is considered to be before the others, etc.

The DVI file contains a number of Pages followed by a Postamble.  Each page
starts with a BOP command, has lots of other commands, and ends with an EOP
command.  Each EOP command is immediatly followed by another BOP command,
or a PST command, which means that there are no more Pages in the file, and
the Postamble follows.  See below for details on all the commands that occur
in Pages, and what goes in the Postamble.

Each Page consists of a number of Commands that specify what characters should
be typeset where.  Who- or what-ever reads these Pages should have a Stack
that can hold, say, 200 coordinates (i.e. integers) to be on the safe side.

Co-ordinates, by the way, are given in R.S.U.'s (rediculously small units),
where 1 rsu = 1/2↑16 points.  This is so that accumulated errors will be
undetectable even in the worst imaginable case (a 'box' many feet long).

The commands are:
(A lower case character with a bracketed number following them means that the
command has a paramater that is that many bytes long, so the BOP command, for
instance, is 9 bytes long, the first byte of which has the decimal value 129,
the second through fifth of which give the page number (high order byte first),
and the sixth through ninth being another number which is explained below.
These numbers are in two's compliment, so they should be sign-extended on
the left when they are read).

Command 	Description
---------------------------
0 to 127	Set the appropriate character from the current font such that
		its reference point is at the current x,y location, and then
		increment the current x-coordinate by the character's width.

128 NOP		No-op, do nothing, ignore.

129 BOP n<4> p<4>
		Begining of page 'n', with pointer 'p' to the BOP command of 
		the PREVIOUS page.  By 'pointer' is meant the relative byte
		number within the DVI file, where the first byte (the BOP of
		the first page) is byte number zero.  If the first page only
		had a BOP and EOP, the THIRD page's pointer would be 9, since
		the BOP commad takes bytes 0 to 7, the EOP is 8, so the SECOND
		page's BOP is in byte 9. Get it?).  The FIRST page has a -1 for
		a pointer.
		Start the x- and y-coordinates out at 0, as well as the xamt,
		yamt, yamt and zamt.  The stack should be empty, and no
		characters will be set before a FONT(NUM) command occurs.
		Remember that n can be < 0, if the page was Roman Numbered.
		Also the pages need not come in the proper order in the file,
		depending on who's doing the TEXing.

130 EOP		The end of all commands for the page has been reached.
		The next page, or the postamble, starts in the next byte.

131 PST		The postamble starts here. See below for the full explanation
		of what goes in the postamble.

132 PUSH	Push the current values of the X- and Y-coordinates, and the
		current w-, x-, y- and z-amounts onto the stack, but don't
		alter them.

133 POP		Pop the z-, y-, x-, and w-amounts, and the Y- and X-coordinates
		off the stack.

134 VERTRULE h<4> w<4>
		Same as HORZRULE, but also increment the current x-coordinate
		by 'w' when done.

135 HORZRULE h<4> w<4>
		Typeset a rule of height 'h' and width 'w', with its bottom
		left corner at the current x,y position.

136 HORZCHAR c<1>
		Set character 'c' just as above, but don't change the current
		value of the x-coordinate (or y-coordinate, either).

137 FONT f<4>	From now on, set characters from font number 'f'.  Note that
		this command is not currently used by TEX--it is only needed
		if 'f' is greater than 63.  See below.

144 X2 m<2>	Move right 'm' rsu's (note that m is in two's compliment, so
143 X3 m<3>	this could actually be a move to the left), and put 'm' into
142 X4 m<4>	the current x-amount.

145 X0		Move right the current x-amount (which can be negative, etc).

140 W2 m<2>	The same as the X commands, but alter w-amount rather than
139 W3 m<3>	x-amount, so that W0 is different than X0.
138 W4 m<4>

141 W0		Move right the current w-amount.

148 Y2 n<2>	Same idea, but now its "down" rather than "right".
147 Y3 n<3>
146 Y4 n<4>

149 Y0		Guess.

152 Z2 m<2>	Another downer.
151 Z3 m<3>
150 Z4 m<4>

153 Z0		Guess again.

154 to 217 FONTNUM's
		Make 0,1,...,63 the current font.

218 to 255 are currently undefined.

Pages need not be sequential by number, but any blank or non-existant page
might not be represented, so page -5's pointer to the 'previous page' might
point to page 34, for instance (remember that TEX uses negative numbers for
roman-numbered pages).  The first page in the file has a 'previous page'
pointer of -1.

The postamble begins with a PST command, followed by four bytes of previous-
page pointer to the last real page, followed by four bytes of the width of the 
widest page (in rsu's), followed by four bytes of the height of the tallest.
Next come a number of Font Definitions (maybe none, if you're an authoritarian),
each of which has a Font ID in the first 4 bytes, followed by 4 bytes of Font
Number, followed by any character not in the font name, followed by the the
Font Name, one character per byte for as many bytes as necessary, followed
followed by that same character that was not in the Font Name (a qoute is
probably a good choice for such a character).  The end of the font definitions
is marked by an ID of -1 (which will not be followed by font number, etc).
The four bytes following this phony ID are a pointer to the PST command (i.e.
the begining of the postamble), which is followed by a zero byte, which is 
followed by a number (guarenteed to be at least 4) of 233 (base ten) bytes.
The reason for some of the above wierdness is twofold:  We will eventually
be producing DVI files with a Pascal program, and to avoid doing any non-serial
I/O, the postamble pointer has to go at the end of the file (Of course, most
programs that read these files need not be generally transportable, and can do
a random seek to the end of the file, and then another to get right to the
postamble).  The fact that page-pointers point backwards is in the same spirit,
but also allow the file to be read in backwards-page-order efficiently.  This,
in turn, will allow for further efficiencies in communicating with your device,
depending on how clever it (and you) is (are).  More details coming....

.ANT = Alphatype Font File, used by Alphatype preprocessor and server.

Due to hardware considerations, each character in an Alphatype Font File might
have to be composed of many smaller pieces, each of which is called a sub-glyph.
The first 128 words (numbers 0 to 127) in the font file contain, in their left
half, the number of sub-glyphs that comprise the appropriate character; and
in the right half, pointers to a list of that many Sub-Glyph Descriptors, where
a "pointer" is just a word number. (Most characters, of course, will be composed
of only one Sub-Glyph.)

Word 128 is an ID number, as in .TFI files.

Word 129 has the 11-bit x-multiplier in its left half, and the y-multiplier
in its right half, both right-justified in those 18-bit fields.

Following word 129 come the Sub-Glyph Descriptors, each of which is four words
long.  The first word has the offset of the reference point of the sub-glyph
relative to the reference point of the character it is part of; the x-offset
going in the left half-word, y-offset in the right.  The second word has the 
"leftmost bit position" in its left half, and the "rightmost bit position" in
its right half.  The third word has the "byte times" in its left half, and a
pointer to the Boundary Descriptor for that sub-glyph in the right half.  Last
is a word containing the width that TEX thinks the character is (from the .TFI
file) in units of 1/2↑18 of a point.

Following all the Sub-Glyph Descriptors come all of the Boundary Descriptors,
each of which has the following format:  First comes a word containing the 
number of bytes of boundary data for the Sub-Glyph, followed by the boundary
data itself.   The boundary data is packed four 8-bit bytes in the low order 32 
bits of each 36 bit word, with the first byte occupying the 5th- through 12th-
most significant bits of the word.  As many consecutive words as are necessary
are used to hold all the boundary data.  ( The number should be ceiling((number
of bytes of boundary data)/4) ).

The reason that each Sub-Glyph Descriptor has a pointer to a Boundary Descriptor
rather than just having the latter follow the former, is that the preprocessor
need only look at SGDs, while the server also requires BDs, and the method we
will be using on the 20 to read .ANT files in both programs is such that un-
needed blocks will never be read into memory.  See Dec's "PMAP JSYS" for more.

.VNT = Versatec Font File, used by Versatec preprocessor and server.

The VNT files are made to only use 32 bits of each word, so in the discussion
below, "right half word" means the low order 16 bits of a word, and "left half
word means the next-to-lowest 16 bits, i.e. the 16 bits just below the four
most significant bits in the 36 bit word.

The first 128 groups of four words (numbers 0 to 511) contain information
about the corrosponding characters as follows:  The first word of four has
the number of pixels wide the actual picture of the character is in the left
half-word, and its height in pixels in the right half-word. The second word
contains the offset of the character's upper-left-hand pixel from its reference
point; the x-offset in the left half-word, y-offset in the right half-word.
The third word contains a pointer to the bit raster for the character in its
left half, and points to the bit raster of the character rotated 90 degrees 
clock-wise with its right half.  The fourth word contains the width that TEX
thinks the character is (from the .TFI file) in units of 1/2↑16 of a point.

Word 512 has an ID number, like in .TFI files.

The Bit Rasters begin after word 512.  They only use the low order 32 bits of
each word, and each new raster row must begin in a new word--like the XGP format
for "big" characters.  The final word for each row probably will not be "full"
(unless the pixel width of the character is evenly divisible by 32), in which
case, the most-significant bits are the ones that are valid (not counting the
4 ignored bits), and the unused low order bits will be zero.

Actually, there can be a description of the font begining in word 512, as long
as nothing points to it, and it better end with a control-v if you want vntchr
to work.  Since this is all very 7-bit-ascii dependent, these descriptions are
being removed.
.ALF = Alphatype Preprocessor Output File, given to Alphatype server.

.VER = Versatec Preprocessor Output File, given to Versatec server.

For reasons you really don't want to know (explained below), VER files are sort
of backwards.  

Now for the excuse for this backwardness:  Its all in the name of efficiency.

Random Programs

The program TFXPR makes a .TFD file from a .TFX file.  The former has the
feature that it is readable and editable, and since the program TFDRD will
make a .TFD file back into a .TFX file, there is a way to alter TFX files.

Similarly, VNTCHR makes an editable version of a VNT file, and CHRVNT will
make a VNT file from a CHR file.  NOTE that there is information in VNT files
that is supposed to be redundant with information in the associated TFX file.
(the character-widths, to be specific).  WHEN CHRVNT MAKES A VNT FILE, IT
OPENS THE TFX FILE AND GETS THIS INFORMATION!  Therefor, if you change a TFX
file, you should then remake the VNT file, using VNTCHR and CHRVNT (or just
CHRVNT, if there is already a CHR file around), if you want to get correct
results.

The program DVITYP prints out a one-line per command description of a DVI
file, while DVISET goes through everything necessary to keep track of the
current font, x and y-position, etc., and is especially suited for hacking
into a DVI-to-<your favorite device> translator.